.TH std::tie 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::tie \- std::tie

.SH Synopsis
   Defined in header <tuple>
   template< class... Types >                             \fI(since C++11)\fP
   std::tuple<Types&...> tie( Types&... args ) noexcept;  (constexpr since C++14)

   Creates a tuple of lvalue references to its arguments or instances of std::ignore.

.SH Parameters

   args - zero or more lvalue arguments to construct the tuple from.

.SH Return value

   A std::tuple object containing lvalue references.

.SH Possible implementation

   template <typename... Args>
   constexpr // since C++14
   std::tuple<Args&...> tie(Args&... args) noexcept
   {
       return {args...};
   }

.SH Notes

   std::tie may be used to unpack a std::pair because std::tuple has a converting
   assignment from pairs:

 bool result;
 std::tie(std::ignore, result) = set.insert(value);

.SH Example

   1) std::tie can be used to introduce lexicographical comparison to a struct or to
   unpack a tuple;
   2) std::tie can work with structured bindings:


// Run this code

 #include <cassert>
 #include <iostream>
 #include <set>
 #include <string>
 #include <tuple>

 struct S
 {
     int n;
     std::string s;
     float d;

     friend bool operator<(const S& lhs, const S& rhs) noexcept
     {
         // compares lhs.n to rhs.n,
         // then lhs.s to rhs.s,
         // then lhs.d to rhs.d
         // in that order, first non-equal result is returned
         // or false if all elements are equal
         return std::tie(lhs.n, lhs.s, lhs.d) < std::tie(rhs.n, rhs.s, rhs.d);
     }
 };

 int main()
 {
     // Lexicographical comparison demo:
     std::set<S> set_of_s;

     S value{42, "Test", 3.14};
     std::set<S>::iterator iter;
     bool is_inserted;

     // Unpack a pair:
     std::tie(iter, is_inserted) = set_of_s.insert(value);
     assert(is_inserted);


     // std::tie and structured bindings:
     auto position = [](int w) { return std::tuple(1 * w, 2 * w); };

     auto [x, y] = position(1);
     assert(x == 1 && y == 2);
     std::tie(x, y) = position(2); // reuse x, y with tie
     assert(x == 2 && y == 4);


     // Implicit conversions are permitted:
     std::tuple<char, short> coordinates(6, 9);
     std::tie(x, y) = coordinates;
     assert(x == 6 && y == 9);
 }

.SH See also

   Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple
                              elements of the initializer
   make_tuple                 creates a tuple object of the type defined by the
   \fI(C++11)\fP                    argument types
                              \fI(function template)\fP
   forward_as_tuple           creates a tuple of forwarding references
   \fI(C++11)\fP                    \fI(function template)\fP
   tuple_cat                  creates a tuple by concatenating any number of tuples
   \fI(C++11)\fP                    \fI(function template)\fP
   ignore                     placeholder to skip an element when unpacking a tuple
   \fI(C++11)\fP                    using tie
                              (constant)
